The Serial Port primitives allow you to send and receive ASCII data easily through the serial ports of your Macintosh. They are well-suited to the situation where you know you will only be sending ASCII data, it will be done only through the serial ports directly (never through a modem or the network), and no communications protocols (XModem, ZModem) are involved. If you need to support protocols, binary file transfers, or multiple transfer mediums, the Prograph Communications Toolbox may be more appropriate to the task.
The standard serial ports are generally on the back of the machine and are labelled with pictures of a printer and a telephone. Cards are also available that extend the serial port capabilities of the machine. You need a cable to connect the serial port to the equipment you are communicating with. Each port can be opened to receive or send data, or both.
Serial port communications can be used to interface with many kinds of instrumentation and other peripherals. If a piece of equipment can be controlled through a serial port, the manufacturer generally publishes a specification for the format of the commands or data that it understands.
Loading the Serial Port Primitives
The Serial Port primitives are stored in the Communication Primitives file. This is located within the Disabled Primitives folder, a subfolder within the Prograph Extensions folder. These primitives are not initially loaded with Prograph Classic, as packaged.
NOTE: The Communication Primitives file also contains the AppleTalk primitives.
In order to use the Serial Port primitives, shut down Prograph, move the Communication Primitives file into the Prograph Extensions folder. You may have to increase Prograph's minimum memory allocation using the Finder's Get Info dialog. The Serial Port primitives will be available the next time you start Prograph.
Using the Serial Port Primitives
To use the primitives, first call open-serial-port for every port you intend to use; this returns a PortNum which you then pass into subsequent primitive calls that affect that port. Call configure-sport if you want configuration settings other than the defaults. Sending data is easy - just call send-serial-port. The data is sent in chunks asynchronously, so you should poll periodically with send-sport-done to see if the data have finished transmitting.
Receiving data is also done asynchronously. Use count-sport-input to see if any data has arrived on the incoming serial port, ready to read. If it is nonzero, read the data received with receive-serial-port. Sometimes it will take several calls to these two to receive all the data in the transmission.
Finally, before exiting the application, call close-serial-port for every PortNum that you opened.
Most of the Serial Port primitives return an ErrorCode. This will be 0 if the operation succeeded. There are many possible error codes that could be returned if the operation failed - see Inside Macintosh for a complete list of possibilities.
The Serial Port Primitives file must be in your Prograph Extensions folder for the primitives to becomne available in the Prograph interpreter environment.
_________________________________________________
 
break-serial-port *324*
Input types: integer; boolean
Output type: integer
Description: Sets the break signal on the given PortNum. If Break is TRUE, turns the break signal on. If Break is FALSE, turns the break signal off.
_________________________________________________
 
close-serial-port *324*
Input type: integer
Output type: integer
Description: Closes the port represented by PortNum. Always call when finished with a serial port.
See also: open-serial-port
_________________________________________________
 
configure-sport *325*
Input types: integer; list
Output type: integer
Description: Sets the configuration of the serial port PortNum. Configuration is a list of strings, consisting of one or more of the following:
For baud rate: "baud300", "baud600", "baud1200", "baud1800", "baud2400", "baud3600", "baud4800", "baud7200", "baud9600", "baud19200" or "baud57600"
For data bits: "data5", "data6", "data7" or "data8"
For parity: "evenParity", "noParity" or "oddParity"
For stop bits: "stop10", "stop15" or "stop20"
For CTS hardware handshaking: "CTSOn" or "CTSOff"
For output flow control flag: "XOn" or "XOff"
If any of the above six settings are omitted, that setting remains unchanged for the port. The default configuration when a port is opened is ("baud9600" "data8" "noParity" "stop20" "CTSOff" "XOff").
Example: A Configuration of (“baud2400” “data7” “oddParity”) sets the port for 2400 baud, 7 bit data and odd parity; the stop bits, CTS and XOn/XOff flags remain at whatever their current setting.
See also: sport-configuration
_________________________________________________
 
count-sport-input *325*
Input type: integer
Output type: integer
Description: Input size is the number of characters which are available to be read from the serial port. Use receive-serial-port to read the data.
See also: get-sport-buffer, receive-serial-port, set-sport-buffer
_________________________________________________
 
get-sport-buffer *326*
Input types: integer
Output type: integer
Description: Buffer size is the size of the input buffer of the serial port.
See also: set-sport-buffer, receive-serial-port, count-sport-input
_________________________________________________
 
get-sport-refs *326*
Input types: integer
Output types: integer; integer
Description: Returns the driver ref numbers of the output and input drivers of an open serial port. These ref numbers are created by open-serial-port when it calls OpenDriver. An unopened driver will have a ref number of 0.
_________________________________________________
 
kill-serial-port *326*
Input types: integer; string
Output type: integer
Description: Kills any pending input or output (or both) on the serial port. Driver can be “in”, “out” or “both”.
_________________________________________________
 
open-serial-port *327*
Input types: string; [string]
Output types: integer; integer
Description: Opens a serial port and returns a PortNum. The default serial port driver names are “.AIn” and “.AOut” for the modem port, and “.BIn” and “.BOut” for the printer port. You may open a port for both input and output by passing in both driver names. Non-default driver names are usually available in documentation provided by the board's manufacturer.
See also: close-serial-port
_________________________________________________
 
receive-serial-port *327*
Input types: integer; integer
Output type: string; integer
Description: Receives Count characters from the serial port. Data is NULL if the receive operation failed. Use count-sport-input to find out how many characters are available to be read from the serial port.
See also: count-sport-input, set-sport-buffer
_________________________________________________
 
send-serial-port *327*
Input names: PortNum; Data; [NumTries]
Input types: integer; string; [integer]
Defaults: NumTries = 100
Output name: ErrorCode; [Success]
Output type: integer; [boolean]
Description: Sends the data string asynchronously to the serial port. NumTries is the number of times to try to find a free parameter block. Parameter blocks are released when data is received. Success is FALSE if all parameter blocks are in use. If no second output, operation fails instead of returning FALSE for Success. Use send-sport-done to check whether output is complete.
See also: send-sport-done
_________________________________________________
 
send-sport-done *328*
Input type: integer
Output type: boolean
Description: Checks whether all asynchronous output is complete. Done is TRUE if all output to the port is complete, FALSE if output is pending.
See also: send-serial-port
_________________________________________________
 
set-sport-buffer *328*
Input types: integer; integer
Output type: integer
Description: Creates a new input buffer for a serial port. If BufferSize is zero, the default buffer is used (1024 bytes). Set the buffer to a larger size to prevent the buffer filling up when you are receiving large amounts of data; if the buffer fills up, data will be lost.
See also: count-sport-input, get-sport-buffer, receive-serial-port
_________________________________________________
 
sport-configuration *328*
Input type: integer
Output type: list
Description: Configuration is a list of strings representing the current settings on the serial port. The list contains one string for each of the following settings: baud rate, stop bits, data bits, parity, XOn/XOff flow control and CTS hardware handshaking.
